Inside Macintosh: Sound

Using Double Buffers

The play-from-disk routines make extensive use of the SndPlayDoubleBuffer function. You can use this function in your application directly if you wish to bypass the normal play-from-disk routines. You might want to do this to maximize the efficiency of your application while maintaining compatibility with the Sound Manager. Or, you might define your own double-buffering routines so that your application can convert 16-bit sound data on disk to 8-bit data that all versions of the Sound Manager can play. By using SndPlayDoubleBuffer instead of the normal play-from-disk routines, you can specify your own doubleback procedure (that is, the algorithm used to switch back and forth between buffers) and customize several other buffering parameters.

SndPlayDoubleBuffer is a very low-level routine and is not intended for general use. In most cases, you should use the high-level Sound Manager routines (such as SndPlay or SndStartFilePlay ) or standard sound commands (such as bufferCmd ) to play sounds. You should use SndPlayDoubleBuffer only if you require very fine control over double buffering. Remember also that the SndPlayDoubleBuffer function is not always available. You'll need to ensure that it's available in the current operating environment before calling it. See "Testing for Multichannel Sound and Play-From-Disk Capabilities" for details.

You call SndPlayDoubleBuffer by passing it a pointer to a sound channel (into which the double-buffered data is to be written) and a pointer to a sound double buffer header record. Here's an example:



 
myErr := SndPlayDoubleBuffer(mySndChan, @myDoubleHeader);

A sound double buffer header record has the following structure:



 
TYPE SndDoubleBufferHeader =

PACKED RECORD

    dbhNumChannels:         Integer;        {number of sound channels}

    dbhSampleSize:          Integer;        {sample size, if noncompressed}

    dbhCompressionID:       Integer;        {ID of compression algorithm}

    dbhPacketSize:          Integer;        {number of bits per packet}

    dbhSampleRate:          Fixed;          {sample rate}

    dbhBufferPtr:           ARRAY[0..1] OF SndDoubleBufferPtr;

                                            {pointers to SndDoubleBuffer}

    dbhDoubleBack:          ProcPtr;        {pointer to doubleback procedure}

END;

The values for the dbhCompressionID , dbhNumChannels , and dbhPacketSize fields are the same as those for the compressionID , numChannels , and packetSize fields of the compressed sound header, respectively.

The dbhBufferPtr array contains pointers to two records of type SndDoubleBuffer . These are the two buffers between which the Sound Manager switches until all the sound data has been sent into the sound channel. When the call to SndPlayDoubleBuffer is made, the two buffers should both already contain a nonzero number of frames of data.

The Sound Manager defines the data type SndDoubleBufferHeader2 that is identical to the SndDoubleBufferHeader data type except that it contains the dbhFormat field (of type OSType ) that defines a custom codec to be used to decompress the sound data. The dbhFormat field is used only if the dbhCompressionID field contains the value fixedCompression . See "Sound Double Buffer Header Records" for details.

Here is the structure of a sound double buffer:



 
TYPE SndDoubleBuffer =

PACKED RECORD

    dbNumFrames:        LongInt;            {number of frames in buffer}

    dbFlags:            LongInt;            {buffer status flags}

    dbUserInfo:         ARRAY[0..1] OF LongInt;

                                            {for application's use}

    dbSoundData:        PACKED ARRAY[0..0] OF Byte;

                                            {array of data}

END;

The buffer status flags field for each of the two buffers might contain either of these values:



 
CONST

    dbBufferReady           = $00000001;

    dbLastBuffer            = $00000004;

All other bits in the dbFlags field are reserved by Apple; your application should not modify them.

The following two sections illustrate how to fill out these data structures, create your two buffers, and define a doubleback procedure to refill the buffers when they become empty.

Setting Up Double Buffers

Writing a Doubleback Procedure